home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 22 / Cream of the Crop 22.iso / os2 / npswp182.zip / NPSWPSWA.DOC < prev    next >
Text File  |  1996-04-29  |  10KB  |  259 lines
  1.     NPS WPS Enhancer version 1.81 Window Animation Manual
  2.  
  3.  
  4. [Outline]
  5.  
  6.   NPS WPS Enhancer loads DLLs written in NPSWPS.LST for window animations
  7. when it starts.  So the programmers who can write a DLL can add his or her
  8. own window animation DLL.  This document shows how to create window animations.
  9.  
  10.  
  11. [Definitions of function and structure]
  12.  
  13.   Please see NPSWPSWA.H first.  This file contains the necessary definitions
  14. to create window animations.  Window animation functions must be declared
  15. like this:
  16.  
  17.   BOOL EXPENTRY windowAnimation(struct AnimationData *pAnimationData);
  18.  
  19.  
  20.   "AnimationData" is the structure used for window animation functions.
  21. This structure contains these variables listed below.
  22.  
  23. HPS hps;
  24.   The presentation space handle of the entire screen.
  25.  
  26. HWND hwnd;
  27.   The window handle of the opening window.  If the animation function is called
  28. for the closing window,  this variable is set to NULLHANDLE.
  29.   The opening window is prohibited from drawing its window by
  30. WinLockWindowUpdate.
  31.  
  32. RECTL rectWindow;
  33.   The rectangle data which stands for the position and the size of the window
  34. in the screen coordinates.
  35.  
  36. POINTL ptCenter;
  37.   The position of the window center.  This data is calculated as follows:
  38. ptCenter.x = (rectWindow.xLeft + rectWindow.xRight) / 2,
  39. ptCenter.y = (rectWindow.yBottom + rectWindow.yTop) / 2.
  40.  
  41. POINTL ptRelRightTop;
  42.   The position of the right top corner of the window in the window coordinates.
  43. ptRelRightTop.x = rectWindow.xRight - ptCenter.x,
  44. ptRelRightTop.y = rectWindow.yTop - ptCenter.y.
  45.  
  46. BOOL fOpen;
  47.   TRUE if the animation function is called for the opening window, FALSE for
  48. the closing window.
  49.  
  50. enum AnimationCallType animCallType;
  51.   What the animation function is called for.  This variable is set to
  52. "AnimationInitialize" to initialize the function for one opening or closing
  53. animation, "AnimationDraw" to draw the picture, "AnimationErase" to erase the
  54. picture, and "AnimationTerminate" to terminate the animation.
  55.  
  56. LONG lStep;
  57.   The current step of the animation.  This value ranges 1 to cTotalSteps
  58. (see below).
  59.  
  60. LONG cTotalSteps;
  61.   The total steps of each animation type.  The user can change this value with
  62. the animation dialog box.
  63.  
  64. LONG cAfterimages;
  65.   The number of afterimages.  The user can change this value with the notebook.
  66.  
  67. LONG lParameter;
  68.   The parameter for each animation function.  For instance, this value means
  69. the rotation angle for Spin Frame, and means frame divisor for Scatter / Gather
  70. Frames.  The user can change this value with the dialog box, too.
  71.  
  72. LONG lVersion;
  73.   NPS WPS Enhancer's version. This value is calculated as follows:
  74. lVersion = MajorVersion x 1000 + MinorVersion x 10 + Revision
  75. For example, NPS WPS Enhancer version 1.81 sets this value to 1810, and
  76. version 2.71a will set this value to 2711, etc.
  77.   This variable is available with NPS WPS Enhancer version 1.81 or later.
  78.  
  79. RECTL rectScreen;
  80.   The rectangle data which stands for the size of the entire screen.
  81. The values rectScreen.xLeft and rectScreen.yBottom are always set to 0.
  82.   This variable is available with NPS WPS Enhancer version 1.81 or later.
  83.  
  84. LONG alReserved[27];
  85.   Do not use it. It is reserved for the future version.
  86.  
  87. CHAR achBuffer[4000];
  88.   The free data area for the window animation.  You can store the data
  89. necessary to draw a window animation.
  90.  
  91.  
  92. [How animation functions are called]
  93.  
  94.   The function to draw the animation is randomly selected every time a window
  95. is opening or closing, from the enabled animation functions.
  96.  
  97.   When NPS WPS Enhancer intercepts the message which says a window is now
  98. opening or closing,  the program gets the HPS of the screen and set its
  99. foreground mix mode to FM_INVERT.
  100.   And after AnimationData is properly set, the animation function is called
  101. with the call type (animCallType) of AnimationInitialize.  The animation
  102. function has to initialize itself for the animation of this window, and return
  103. the BOOL value.
  104. The function stores the animation data to achBuffer if necessary.
  105.   If FALSE is returned, NPS WPS Enhancer try to initialize another animation
  106. function. If it fails to initialize three times in a row, the window animation
  107. doesn't occur for this window at all.
  108.   If TRUE is returned, the animation begins.
  109.  
  110.   The animation function is called twice for each step; once to draw the
  111. picture, once to erase it.  The pointer to AnimationData points the same data
  112. used in the initialization call.
  113.  
  114.   When opening, the step (lStep) is incremented from 1 to the total steps
  115. (cTotalSteps). When closing, the step is decremented from the total steps to 1.
  116.   The function call to erase the picture is delayed from the call to draw
  117. according to the setting of the number of afterimages.
  118.  
  119.   For example, the parameters for the opening animations are shown below where
  120. the total step is set to 100, and the number of afterimages is set to 1.
  121.  
  122.   Orderç    Step    Calling Type (animCallType)
  123.     1         1       draw    (afterimage: 1)
  124.     2         1       erase
  125.     3         2       draw
  126.     4         2       erase
  127.     5         3       draw
  128.     6         3       erase
  129.     7         4       draw
  130.     8         4       erase
  131.  
  132.    ...
  133.  
  134.   197        99       draw 
  135.   198        99       erase
  136.   199       100       draw
  137.   200       100       erase   (afterimage: 0)
  138.  
  139.   If the number of afterimages is set to 3 in this case, these parameters are
  140. set as follows.
  141.  
  142.   Orderç    Step    Calling Type
  143.     1         1       draw    (afterimage: 1)
  144.     2         2       draw    (afterimage: 2)
  145.     3         3          draw    (afterimage: 3)
  146.     4         1       erase
  147.     5         4       draw
  148.     6         2       erase
  149.     7         5       draw
  150.     8         3       erase
  151.  
  152.    ...
  153.  
  154.   193        98       draw
  155.   194        96       erase
  156.   195        99       draw
  157.   196        97       erase
  158.   197       100       draw
  159.   198        98       erase   (afterimage: 2)
  160.   199        99       erase   (afterimage: 1)
  161.   200       100       erase   (afterimage: 0)
  162.  
  163.   The parameters for the closing animations are shown below where
  164. the total step is set to 100, and the number of afterimages is set to 1.
  165.  
  166.   Orderç    Step    Calling Type
  167.     1       100       draw    (afterimage: 1)
  168.     2       100       erase
  169.     3        99       draw
  170.     4        99       erase
  171.     5        98       draw
  172.     6        98       erase
  173.     7        97       draw
  174.     8        97       erase
  175.  
  176.    ...
  177.  
  178.   197         2       draw 
  179.   198         2       erase
  180.   199         1       draw
  181.   200         1       erase   (afterimage: 0)
  182.  
  183.   If the number of afterimages is set to 3 in this case, these parameters are
  184. set as follows.
  185.  
  186.   Orderç    Step    Calling Type
  187.     1       100       draw    (afterimage: 1)
  188.     2        99       draw    (afterimage: 2)
  189.     3        98          draw    (afterimage: 3)
  190.     4       100       erase
  191.     5        97       draw
  192.     6        99       erase
  193.     7        96       draw
  194.     8        98       erase
  195.  
  196.    ...
  197.  
  198.   193         3       draw
  199.   194         5       erase
  200.   195         2       draw
  201.   196         4       erase
  202.   197         1       draw
  203.   198         3       erase   (afterimage: 2)
  204.   199         2       erase   (afterimage: 1)
  205.   200         1       erase   (afterimage: 0)
  206.  
  207.  
  208.   If you think it's too complex (I think so!), just ignore whether opening or
  209. closing, whether drawing or erasing, and the number of afterimages.
  210. Draw the same picture for the same step count instead.  Because the animation
  211. function is always called twice for the same step, and the mix mode is set to
  212. INVERT, this way of drawing guarantees that the picture is always properly erased.
  213. And it also guarantees the movement of closing animation is exactly the reverse
  214. of one of opening animation.  I used this way in all animation functions in
  215. NPSWPSWA.CPP.  
  216.  
  217.   Animation functions have to return TRUE if it wants to continue animation for
  218. further step.  If FALSE is returned, the animation is aborted immediately.
  219.  
  220.   After the drawing and erasing the animation, the animation function is called
  221. again with call type of "AnimationTerminate".  In this termination call you
  222. can clean up resources if any.  This termination is always called if the
  223. initialization is successfully returned. (Even if the animation is aborted.)
  224.  
  225.   I didn't use the termination call in NPSWPSWA.CPP, and just returns TRUE.
  226.  
  227.  
  228. [How to register window animation functions]
  229.  
  230.   First, animation functions must be exported in a DLL, not by their names
  231. but by their DLL ordinals.  See NPSWPSWA.DEF for a sample.
  232.  
  233.   The format of NPSWPS.LST is described below. Each strings are separated by
  234. a white space.
  235.  
  236. DLL-Name DLL-Ordinal "Animation Name" "Parameter Name" "Displayed Animation Name" "Displayed Parameter Name" Default-Step Default-Parameter Minimum-Parameter Maximum-Parameter
  237.  
  238.   The line which starts with a semicolon is ignored.  "Animation name" and
  239. "Parameter Name" must be the English words for the worldwide compatibility.
  240. To avoid conflict of animation names, please included the writer's name in
  241. the animation name if possible. For example, "Takasugi's Spin Frame", etc.
  242.   "Displayed Animation Name" and "Displayed Parameter Name" are used for the
  243. strings in the animation dialog box.  The user can modify these strings.
  244.  
  245.   Default-Step and Default-Parameter are used for the settings at the first
  246. time the DLL is loaded.  Once loaded, NPS WPS Enhancer will store the animation
  247. settings in NPSWPS.INI.
  248.  
  249.  
  250. [Other]
  251.  
  252.   If you have something to ask about window animations, please send me an
  253. email.  I'm looking forward to seeing your nice animations.
  254.  
  255.  
  256.             Shinji 'N.P.S.' Takasugi     Team OS/2 Japan
  257.             nps1970@ibm.net
  258.             JBD03575@niftyserve.or.jp (for Japanese users)
  259.